home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / basic / qlib.exe / DISK.DOC < prev    next >
Encoding:
Text File  |  1992-02-25  |  24.7 KB  |  701 lines
  1.     DISK / FILE routines look for specified files on your disk, or report
  2.     disk status.  Several QLIB disk/file subroutines return the following
  3.     MS-DOS error codes:
  4.  
  5.         oops% = 1          file name is a nul string
  6.         oops% = 2          file not found
  7.         oops% = 3          path not found
  8.         oops% = 4          too many open files
  9.         oops% = 5          access denied (file may be read-only
  10.                             or a subdirectory, or subdirectory not empty)
  11.         oops% = 19         disk is write-protected
  12.  
  13.     BIOS error codes, returned by DriveReady, are:
  14.  
  15.         oops% = 2          disk not readable (not formatted, or wrong type)
  16.         oops% = 128        drive not ready
  17.  
  18.  
  19.     File attributes may be combined.  Each bit of the file attribute
  20.     means:
  21.  
  22.         0 = normal files
  23.         1 = read-only
  24.         2 = hidden files
  25.         4 = system files
  26.         8 = volume label (only one per disk - may not be
  27.                           reliable)
  28.        16 = subdirectories
  29.        32 = archive bit set
  30.  
  31.      Thus a file attribute of 18 is a hidden subdirectory (16 OR 2)
  32.  
  33.  
  34.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  35.  
  36.      Subroutine: CopyFile(FromFile$, ToFile$, oops%)
  37.      object file: copyfile.obj (qalloc.obj)
  38.  
  39.           Copies a file from FromFile$ to ToFile$, and returns an error
  40.      code if something went wrong.  FromFile$ and ToFile$ may not include
  41.      any wildcard characters (such as * and ?).  CopyFile will destroy any
  42.      previously-existing file named ToFile$ before copying the file.
  43.      Oops% = -1 if an error in the "To" file was encountered; other error
  44.      codes apply to the "From" file.
  45.  
  46.      Example:
  47.           FromFile$ = "b:\qlib.lib"
  48.           ToFile$ = "c:\qb4\qlib.lib"
  49.           CALL CopyFile(FromFile$, ToFile$, oops%)
  50.  
  51.  
  52.  
  53.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  54.  
  55.      Subroutine: DriveReady(drv$, oops%)
  56.      object file: drvready.obj
  57.  
  58.           DriveReady is used to determine if a floppy disk drive has a usable
  59.      disk and is ready for use.  DriveReady returns BIOS error codes, or
  60.      oops% = 0 if the drive is ready.  Oops% = -1 if drv$ is an invalid
  61.      drive specification.
  62.  
  63.      Example:
  64.           drv$ = "a:"
  65.           CALL DriveReady(drv$, oops)
  66.           IF oops% <> 0 THEN PRINT "Drive " + drv$ + "not ready or bad disk"
  67.  
  68.  
  69.  
  70.  
  71.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  72.  
  73.      Subroutine: DriveSpace(drv$, total&, free&, oops%)
  74.      object file: drvspace.obj
  75.  
  76.           Returns the amount of total and free space left on a given disk
  77.      drive.  The drive string may be any legal disk drive, or "@" (AT sign)
  78.      for the default drive, and must be at least one character long.  An
  79.      illegal drive or other error will cause oops% to be returned as -1.
  80.      Note that total& and free& are LONG integers.  Works with logical
  81.      devices up to 2,147 Megabytes.
  82.  
  83.      Example:
  84.           drv$="C:"
  85.            .
  86.            .
  87.           CALL DriveSpace(drv$, total&, free&, oops%)
  88.           IF oops% = -1 THEN
  89.                   PRINT "Invalid drive specification"
  90.                   ELSE
  91.                   PRINT "Free space on drive "; drv$; " is"; free&; "bytes."
  92.                   PRINT "Total space on drive "; drv$; " is"; total&; "bytes."
  93.           END IF
  94.  
  95.  
  96.  
  97.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  98.  
  99.      Subroutine: Exist(filename$, oops%)
  100.      object file: exist.obj
  101.  
  102.           Tells you if a given file already exists.  Returns an error code
  103.      if it doesn't, or -1 if it does.  Requires an ASCIIZ filename without    
  104.      wildcards.
  105.  
  106.      Example:
  107.        filename$="TEST.TXT" + CHR$(0)
  108.        CALL Exist(filename$, oops%)
  109.        IF oops% = -1 THEN PRINT "File already exists"
  110.        IF oops% = 0 THEN PRINT "Path exists"
  111.                                   ' Filename$ = "d:\path" + CHR$(0)
  112.        IF oops% = 2 THEN PRINT "Path found, file not found"
  113.        IF oops% = 3 THEN PRINT "Path or file not found"
  114.  
  115.  
  116.  
  117.  
  118.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  119.  
  120.      Subroutine: FFlush (handle%)
  121.      object file: fflush.obj (q$error.obj)
  122.  
  123.           Flushes the DOS file output buffer associated with handle%.
  124.      The file must have been opened with QLIB's FOpen or FCreate functions.
  125.      Flushing the file buffer protects against unintended system failures
  126.      such as power outages.  Any data written to the file before calling
  127.      fflush will be safely written to the disk.  FFlush also updates
  128.      QLIB's DOSError flag.
  129.  
  130.      Example:
  131.        REM $INCLUDE: 'qlib.bi'
  132.        f$ = "anyold.fil" + CHR$(0)
  133.        handle% = FCreate (f$)
  134.        ' program writes data to the file
  135.        .
  136.        .
  137.        .
  138.        CALL FFlush (handle%)
  139.  
  140.  
  141.  
  142.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  143.  
  144.      Function: count% = FileCount(s$, attr%)
  145.      object file: findfile.obj
  146.  
  147.           Counts the number of files matching the filespec s$.  S$ must be
  148.      an ASCIIZ (zero-terminated) string and may contain the wildcard
  149.      characters * and ?.
  150.  
  151.      Example:
  152.        REM $INCLUDE: 'qlib.bi'
  153.        s$ ="*.*" + CHR$(0)        ' count all files in the current directory
  154.        attr% = 0                  ' normal files only
  155.        count% = FileCount(s$, attr%)
  156.  
  157.  
  158.  
  159.  
  160. QLIB's file Input/Output subroutines provide fast, flexible file handling,
  161. replacing BASIC's clumsy functions.  These subroutines return an error code
  162. (oops%) which is zero if no error occurred, or returns an MS-DOS error
  163. code if something went wrong.
  164.  
  165. Below is a summary of QLIB's file I/O subroutines:
  166.  
  167.      FOpenR      Open a file for input
  168.      FOpenW      Open a file for output
  169.      FOpenRW     Open a file for random access
  170.      FCreate     Make a new file and open it for I/O
  171.      FClose      Close a file opened by FOpen
  172.  
  173.      FileRead1   Read one byte from a file opened by FOpen
  174.      FileRead2   Read 2 bytes from a file opened by FOpen
  175.      FileRead4   Read 4 bytes from a file opened by FOpen
  176.      FileRead8   Read 8 bytes from a file opened by FOpen
  177.      FileRead    Read from a file opened by FOpen to an array
  178.  
  179.      FileWrite1  Write one byte to a file
  180.      FileWrite2  Write 2 bytes to a file
  181.      FileWrite4  Write 4 bytes to a file
  182.      FileWrite8  Write 8 bytes to a file
  183.      FileWrite   Write data to a file directly from an array
  184.  
  185.      FileBegin   Reset the MS-DOS file pointer to the beginning of
  186.                  the file
  187.      FileEnd     Sets the MS-DOS file pointer to end of the file,
  188.                  to append data to the file
  189.      FileSetPTR  sets the file pointer for an open file to a specified
  190.                  byte position in the file
  191.      FileMovPTR  moves the file pointer forward or backward in the file
  192.  
  193.  
  194.  
  195.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  196.  
  197.      Subroutine: FileBegin(handle%, oops%)
  198.      object file: fileptr.obj
  199.  
  200.          Sets the MS-DOS file pointer to the beginning of a file opened
  201.      by FOpen. Handle% is the file handle returned by FOpen.
  202.  
  203.      Example:
  204.          CALL FileBegin(handle%, oops%)
  205.  
  206.  
  207.  
  208.  
  209.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  210.  
  211.      Subroutine: FClose(handle%)
  212.      object file: fopen.obj
  213.  
  214.          Closes a file opened by FOpen or FCreate.  Handle% is the file
  215.      handle returned by FOpen.  FClose updates the DosError flag.
  216.  
  217.      Example:
  218.          CALL FClose(handle%)
  219.  
  220.  
  221.  
  222.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  223.  
  224.      Function: handle% = FCreate(file$)
  225.      object file: fopen.obj
  226.  
  227.          Creates a new file and returns a handle for subsequent writing.
  228.      If the file already exists, it will be truncated to zero bytes by
  229.      FCreate.  FCreate updates DosError.
  230.  
  231.      Example:
  232.          REM $INCLUDE: 'qlib.bi'
  233.          file$ = "anyold.dat" +CHR$(0)
  234.          handle% = FOpenW(file$)     ' first try to open an existing file
  235.          IF DosError = 2 THEN
  236.             handle% = FCreate(file$) ' create a new file if "anyold.dat"
  237.                                      ' is not found
  238.          ENDIF
  239.  
  240.  
  241.  
  242.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  243.  
  244.      Subroutine: FileEnd(handle%, oops%)
  245.      object file: fileptr.obj
  246.  
  247.          Sets the MS-DOS file pointer at the end of the file.  Subsequent
  248.      FileWrite calls will add new data to the end of the file.
  249.  
  250.      Example:
  251.          file$ = "anyfile.dat" + CHR$(0)
  252.          acode = 1              ' I want to add new data to this file
  253.          handle% = FOpenW(a$)
  254.          CALL FileEnd(handle%, oops%)
  255.  
  256.  
  257.  
  258.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  259.  
  260.      Subroutine: FileMovPTR(handle%, bytes0&, bytes1&, oops)
  261.      object file: fileptr.obj
  262.  
  263.          Moves the file pointer from its present position forward or
  264.      backward in the file.  The file must have been opened by FOpen
  265.      or FCreate.  Bytes0& is the number of bytes to move the pointer,
  266.      and bytes1& is the resulting pointer location in the file.  Note that
  267.      bytes0& and bytes1& are LONG integers.
  268.  
  269.      Example:
  270.          CALL FileMovPTR(handle%, bytes0&, bytes1&, oops%)
  271.  
  272.  
  273.  
  274.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  275.  
  276.      Function: handle% = FOpenR(file$)
  277.      Function: handle% = FOpenRW(file$)
  278.      Function: handle% = FOpenW(file$)
  279.      object file: fopen.obj
  280.  
  281.          The FOpen functions open an existing file for input, output or
  282.      random I/O.  With FOpenR, access is input (Read), FOpenW access
  283.      is output, (Write) and FOpenRW access may be either input or output
  284.      (Read/Write).  File$ is an ASCIIZ (zero-terminated) file name.  Handle%
  285.      is the file handle returned by FOpen for use with subsequent input
  286.      from or output to the file.  When a file is opened by FOpen, the
  287.      MS-DOS file pointer is positioned at the start of the file.  Use
  288.      FileEnd to position the pointer at the end of the file, for appending
  289.      the file.
  290.  
  291.      Example:
  292.         File$ = "anyold.fil" + CHR$(0)
  293.         handle% = FOpenRW(file$)
  294.  
  295.  
  296.  
  297.  
  298.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  299.  
  300.      Subroutine: FileRead(handle%, aSEG%, aPTR%, bytes0%, bytes1%, oops%)
  301.      object file: fileio.obj
  302.  
  303.          Reads bytes0% bytes of data from a file opened by FOpen and
  304.      loads the data into an array beginning at the address pointed to
  305.      by aSEG% and aPTR%.  bytes1% is the number of bytes actually read
  306.      into the array.  Unless FileRead encounters the end of the file,
  307.      bytes1% should be the same as bytes0%.
  308.  
  309.      Example:
  310.         DIM a(99)               ' an integer array of 100 elements
  311.         bytes0% = 200           ' each integer is 2 bytes
  312.         file$ = "anyold.dat" + CHR$(0)
  313.         handle% = FOpenR(file$)
  314.         aSEG% = VARSEG(a(0))    ' start at beginning of file
  315.         aPTR% = VARPTR(a(0))
  316.         CALL FileRead(handle%, aSEG%, aPTR%, bytes0%, bytes1%, oops%)
  317.  
  318.  
  319.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  320.  
  321.      Subroutine: FileRead1(handle%, n%, bytes%, oops%)
  322.      Subroutine: FileRead2(handle%, n%, bytes%, oops%)
  323.      Subroutine: FileRead4(handle%, n& (or n!), bytes%, oops%)
  324.      Subroutine: FileRead8(handle%, n#, bytes%, oops%)
  325.      object file: filerw.obj
  326.  
  327.         FileRead[n] subroutines write a single data point to the file
  328.      opened by FOpen.  FileRead1 is intended for character or short
  329.      integer data, FileRead2 is for INTEGER data, FileRead4 is for LONG
  330.      or SINGLE data and FileRead8 is for DOUBLE or CURRENCY data.  Note
  331.      that SINGLE or DOUBLE data may be either IEEE format or Microsoft
  332.      Binary Format.  Bytes% returned by FileRead[n] will be 1, 2, 4, or 8
  333.      to confirm proper function of the subroutine.
  334.  
  335.      Example:
  336.           handle% = FOpenR(file$ + CHR$(0))
  337.               .
  338.               .
  339.               .
  340.           n& = 40000&
  341.           CALL FileRead4(handle%, n&, bytes%, oops%)
  342.  
  343.         
  344.  
  345.  
  346.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  347.  
  348.      Subroutine: FileSetPTR(handle%, bytes0&, bytes1&, oops%)
  349.      object file: fileptr.obj
  350.  
  351.          Sets the current location of the file pointer for a file opened
  352.      by FOpen or FCreate.  Bytes0& is the desired position and bytes1&
  353.      is returned by FileSetPTR.  Note that bytes0& and bytes1& and LONG
  354.      integers.
  355.  
  356.      Example:
  357.          CALL FileSetPTR(handle%, bytes0&, bytes1&, oops%)
  358.  
  359.  
  360.  
  361.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  362.  
  363.      Subroutine: FileWrite(handle%, aSEG%, aPTR%, bytes0%, bytes1%, oops%)
  364.      object file: fileio.obj
  365.  
  366.          Similar to FileRead, above, but writes to the file from the array.
  367.  
  368.  
  369.  
  370.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  371.  
  372.      Subroutine: FileWrite1(handle%, n%, bytes%, oops%)
  373.      Subroutine: FileWrite2(handle%, n%, bytes%, oops%)
  374.      Subroutine: FileWrite4(handle%, n& (or n!), bytes%, oops%)
  375.      Subroutine: FileWrite8(handle%, n#, bytes%, oops%)
  376.      object file: filerw.obj
  377.  
  378.          Similar to FileRead[n], above, but writes data to the file.
  379.  
  380.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  381.  
  382.      Function: s& = FSize (handle%)
  383.      object file: fsize.obj (d$error.obj)
  384.  
  385.           Given a valid file handle returned by a QLIB FOpen
  386.      subroutine, FSize returns the size of the file.  Any DOS errors
  387.      are flagged by DOSERROR (see DOSERROR in SYSTEM.DOC).
  388.  
  389.      Example:
  390.          REM $INCLUDE: 'qlib.bi'
  391.          handle% = FOpenRW(file$)
  392.          IF DOSERROR THEN . . .       ' error control stuff
  393.          s& = FSize(handle%)
  394.          IF DOSERROR THEN . . .       ' error control stuff
  395.          
  396.  
  397.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  398.  
  399.      Function: d$ = GetDRIVE
  400.      object file: getdrive.obj
  401.  
  402.          Returns the default drive.
  403.  
  404.      Example:
  405.          REM $INCLUDE: 'qlib.bi'
  406.              .
  407.              .
  408.              .
  409.          drive$ = GetDRIVE
  410.          PRINT "The default drive is "; drive$
  411.          REM  drive$ includes the trailing colon, i.e., drive$ = "C:"
  412.  
  413.  
  414.  
  415.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  416.  
  417.      Function: sub$ = GetSUB(d$)
  418.      object file: getsub.obj (q$sdat.obj)
  419.  
  420.          Gets the current directory on disk d$.  To get the current
  421.      directory on the default drive, set d$ = "@".  If d$ specifies an
  422.      invalid drive, sub$ will be a nul string.  NOTE: d$ must be at least
  423.      one character long.
  424.  
  425.      Example:
  426.          REM $INCLUDE: 'qlib.bi'
  427.          d$ = "C:"
  428.          sub$ = GetSUB(d$)
  429.          IF sub$ = "" THEN PRINT d$ + " is not a valid drive"
  430.  
  431.  
  432.  
  433.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  434.  
  435.     Subroutine: FindFirstMatch(file$, fAttr%, oops%)
  436.     Subroutine: FindNextMatch(oops%)
  437.     Subroutine: FindFileName(filename$, flen%)
  438.     Subroutine: FindFileAttr(fAttr%)
  439.     Subroutine: FindFileDate(month%, day%, year%)
  440.     Subroutine: FindFileTime(hour%, min%, sec%)
  441.     Subroutine: FindFileSize(lowword%, highword%)
  442.     object file: findfile.obj
  443.  
  444.          This group of subroutines may be used to search for files which match
  445.     a specified file name.  The specified file name may include drive and
  446.     path, and may also include the * and ? wildcards.  These subroutines may
  447.     be used to duplicate the DOS DIR command.
  448.  
  449.     A search attribute (fAttr%) may also be specified.  File attributes are
  450.     listed on the first page of this file.
  451.  
  452.     fAttr% may include more than one type of file.  For example, if
  453.     fAttr% = 2 + 8, FindFirst/NextMatch will search for hidden and system
  454.     files as well as normal files (normal files will always be found).
  455.     The actual file attribute of the matched file will be returned by
  456.     FindFileAttr.  Files returned may have a combination of attributes; for
  457.     example, if a file attribute returned by FindFileAttr is 18 ( = 2 + 16),
  458.     this file is a hidden directory.
  459.  
  460.     The file size returned by FindFileSize is in two parts.  Use the following
  461.     code to determine the file size:
  462.  
  463.     CALL FindFileSize(lowword%, highword%)  ' assumes file matched with
  464.                                             ' FindFirst/NextMatch, oops% <> 0
  465.     size& = CLNG(lowword%)
  466.     IF lowword% < 0 THEN size& = size& + 65536&
  467.     size& = size& + highword% * 65536&
  468.  
  469.     see examples on the next page
  470.  
  471.  
  472.     Example 1:
  473.          filename$ = SPACE$(12)             ' filename$ must be initialized
  474.                                             ' as a 12-byte (or longer) string
  475.                                             ' or the namelen% will be returned
  476.                                             ' as -1
  477.          FileSpec$ = "\qb4\*.bas"+CHR$(0)   ' FileSpec$ must end in CHR$(0)
  478.          fAttr% = 0                         ' search only for normal files
  479.          CALL FindFirstMatch(FileSpec$, fAttr%, oops%)
  480.          IF oops% = -1 THEN PRINT "FileSpec$ is a nul string"
  481.          IF oops% THEN PRINT "No matching files"
  482.          WHILE oops% = 0
  483.               CALL FindFileName(filename$, namelen%)
  484.               IF namelen% = -1 THEN PRINT "filename$ shorter than 12 bytes"
  485.               PRINT LEFT$(filename$, namelen%)
  486.               CALL FindNextMatch(oops%)
  487.          WEND
  488.          REM  FindFileName, FindFileAttr, FindFileDate, FindFileTime and
  489.          REM  FindFileSize will return usable results only after a successful
  490.          REM  (oops% = 0) call to FindFirstMatch or FindNextMatch.
  491.  
  492.     Example 2:
  493.          REM  In this example, we will print all subdirectories one
  494.          REM  level down from the root directory
  495.          filename$ = SPACE$(12)             ' filename$ must be initialized
  496.                                             ' as a 12-byte (or longer) string
  497.          fAttr% = 16
  498.          FileSpec$ = "\*.*"+CHR$(0)
  499.          CALL FindFirstMatch(FileSpec$, fAttr%, oops%)
  500.          IF oops% THEN PRINT "No files or subdirectories"
  501.          WHILE oops% = 0
  502.               CALL FindFileAttr(fAttr%)
  503.               IF fAttr% AND 16 THEN
  504.                    CALL FindFileName(filename$, namelen%)
  505.                    PRINT LEFT$(filename$, namelen%)
  506.               END IF
  507.               CALL FindNextMatch(oops%)
  508.          WEND
  509.  
  510.  
  511.  
  512.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  513.  
  514.     Function: fseg% = FLoad (filename$ + CHR$(0))
  515.     object files: fload.obj, q$alloc.obj, q$error.obj
  516.  
  517.     FLoad reads a specified file into far memory, returning the segment
  518.     address of the memory block where the file is located.  If an error
  519.     occurs when reading the file, FLoad returns fseg% = 0.  QLIB's
  520.     DOSERROR flag is also updated (see DOSERROR in SYSTEM.DOC).
  521.     If no error occurred, DOSERROR returns 0; otherwise it returns an
  522.     MS-DOS error code.  If fseg% = 0 and DOSERROR = 0 then insufficient
  523.     far memory is available.
  524.  
  525.     Example:
  526.      REM $INCLUDE: '\qb4\qlib.bi'
  527.      filename$ = "\ramfont\italics.fnt" + CHR$(0)
  528.      iseg% = fload (filename$)
  529.      IF DOSError THEN
  530.          .
  531.          .
  532.          .              ; error handling code
  533.  
  534.  
  535.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  536.  
  537.     Subroutine: GetFileAttr(file$ + CHR$(0), attr%, oops%)
  538.     object file: fileattr.obj
  539.  
  540.          Returns the attribute of file$.  File$ must be an ASCIIZ
  541.     (zero-terminated) string without the * or ? wildcards.  File
  542.     attributes are listed on the first page of this file.  Oops%
  543.     is an MS-DOS error code if something went wrong, or oops% = -1
  544.     if no problems were encountered.
  545.  
  546.     Example:
  547.          file$ = "c:\qb4\qlib.lib" + CHR$(0)
  548.          CALL GetFileAttr(file$, attr%, oops%)
  549.  
  550.  
  551.  
  552.  
  553.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  554.  
  555.     Subroutine: KillFile(file$ + CHR$(0), oops%)
  556.     object file: killfile.obj
  557.  
  558.          KillFile deletes file$ from a disk with error trapping, avoiding
  559.     BASIC's ON ERROR.  Note that the file name string passed to the
  560.     subroutine is an ASCIIZ (zero-terminated) string.  Oops% = 0 if
  561.     no error; MS-DOS error codes apply if oops% <> 0.
  562.  
  563.     Example:
  564.          file$ = "oldfile.dat" + CHR$(0)
  565.          CALL KillFile(file$, oops%)
  566.  
  567.  
  568.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  569.  
  570.     Subroutine: KillSUB(sub$ + CHR$(0), oops%)
  571.     object file: killfile.obj
  572.  
  573.          KillSUB deletes subdirectory sub$ from a disk with error trapping,
  574.     avoiding BASIC's ON ERROR.  Note that the directory name string passed
  575.     to the subroutine is an ASCIIZ (zero-terminated) string.  The
  576.     subdirectory must be empty before it is deleted.  Oops% = 0 if
  577.     no error; MS-DOS error codes apply if oops% <> 0.
  578.  
  579.     Example:
  580.          sub$ = "C:\123" + CHR$(0)
  581.          CALL KillSUB(sub$, oops%)
  582.  
  583.  
  584.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  585.  
  586.     Subroutine: MakeSUB(sub$ + CHR$(0), oops)
  587.     object file: killfile.obj
  588.  
  589.       Creates a new subdirectory.  Oops% is an MS-DOS error code returned
  590.     by MakeSUB.  If oops% = 0 then no error was detected.
  591.  
  592.     Example:
  593.       sub$ = "\qb4\qlib"     ' make a new subdirectory for QLIB
  594.       CALL MakeSUB(sub$ + CHR$(0), oops%)
  595.  
  596.  
  597.  
  598.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  599.  
  600.     Subroutine: Rename(old$, new$, oops)
  601.     object file: rename.obj
  602.  
  603.          Changes filename old$ to new$, returning an MS-DOS error code.
  604.     Similar to BASIC's NAME function, but does not require ON ERROR
  605.     to trap errors.  Note that both old$ and new$ must be zero-terminated
  606.     ASCIIZ strings.  You may use Rename to move a file from one directory
  607.     to another on the same disk.
  608.  
  609.     Example:
  610.          old$ = "demo.bas" + CHR$(0)
  611.          new$ = "demo.bak" + CHR$(0)
  612.          CALL Rename(old$, new$, oops)
  613.  
  614.  
  615.  
  616.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  617.  
  618.     Subroutine: SetDRIVE(d$)
  619.     object file: setdrive.obj
  620.  
  621.          Sets d$ as the default drive.  D$ may be any valid disk drive or
  622.     other logical device (such as a RAMdisk).
  623.  
  624.     Example:
  625.          d$ = "a:"           ' the drive specifier d$ may be upper or lower
  626.                              ' case and need not include the colon.
  627.          CALL SetDRIVE(d$)   ' drive A: is now the default drive
  628.  
  629.  
  630.  
  631.  
  632.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  633.  
  634.     Subroutine: SetFileAttr(file$ + CHR$(0), attr%, oops%)
  635.     object file: fileattr.obj
  636.  
  637.          Changes the file attribute of file$.  File attributes are
  638.     described on the first page of this file.  Oops% returned by this
  639.     subroutine is an MS-DOS error code (see first page of this file).
  640.     If all O.K. then oops% = -1.
  641.  
  642.     Example:  I want to make my QLIB.LIB file read-only
  643.  
  644.          REM  I start by getting the present attribute
  645.          file$ = "QLIB.LIB" + CHR$(0)
  646.          CALL GetFileAttr(file$, attr%, oops%)
  647.          IF oops% <> -1 THEN
  648.                 REM  Uh oh, something went wrong
  649.                   .
  650.                   .
  651.                   .
  652.          END IF
  653.  
  654.          REM  now I'll add the Read-only bit to the attribute
  655.          attr% = attr% OR 1
  656.          CALL SetFileAttr(file$, attr%, oops%)
  657.  
  658.  
  659.  
  660.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  661.  
  662.      Subroutine: SetFileDate(file$, month%, day%, year%, hour%, min%, sec%)
  663.      object file: setfdate.obj
  664.  
  665.           Sets file time/date stamp.  The filename must be an ASCIIZ (zero-
  666.      terminated) string.  The year may be either a four digit or two digit
  667.      number  (e.g., either 1986 or just 86).  DOS will round the seconds
  668.      value off to the next lower even number.  If there is a problem with
  669.      the  filename, or if the file is read-only, the month will be returned
  670.      as -1.  Note that midnight is 24:00.  If hour%, minute% and second% are
  671.      all 0, then the file's time will not be displayed in a directory list.
  672.  
  673.      Example:
  674.           file$ = "anyfile.dat" + CHR$(0)
  675.           CALL SetFileDate(file$, month%, day%, year%, hour%, min%, sec%)
  676.  
  677.  
  678.  
  679.  
  680.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  681.  
  682.     Subroutine: SetSUB(sub$ + CHR$(0), oops%)
  683.     object file: killfile.obj
  684.  
  685.          Changes the default subdirectory to sub$.  Oops% is an error
  686.     code returned to BASIC.
  687.  
  688.     SetSUB's error codes:
  689.  
  690.          oops% = 0         no error
  691.                  1         subdirectory name is a nul string
  692.                  3         path not found
  693.  
  694.     Note that sub$ is an ASCIIZ (zero-terminated) string.
  695.  
  696.     Example:
  697.          directory$ = "\qb4\lib" + CHR$(0)
  698.          CALL SetSUB(directory$, oops%)
  699.  
  700.  
  701.